LearningStoreJob.AddOrUpdateItem Method (string, IDictionary<string,object>, IDictionary<string,object>, IDictionary<string,object>, bool)

Add an item, or update the item properties if the item already exists

Parent Type: LearningStoreJob

Namespace: Microsoft.LearningComponents.Storage

Assembly: Microsoft.LearningComponents.Storage.dll

Syntax
C#

public LearningStoreItemIdentifier AddOrUpdateItem (
string itemTypeName,
IDictionary<string,object> uniquePropertyValues,
IDictionary<string,object> propertyValuesToUpdate,
IDictionary<string,object> propertyValuesForAdd,
bool requestItemId

)

Parameters

itemTypeName

The name of the item type to add

uniquePropertyValues

Property values that uniquely identify the item to be added or updated. The key is the property name, and the value is the value of the property.

propertyValuesToUpdate

Property values to be updated if the item is updated, or set if the item is added. The key is the property name, and the value is the value to be placed in the property.

propertyValuesForAdd

Property values to be set if the item is added. The key is the property name, and the value is the value to be placed in the property. If null, then no extra values will be set if the item is added.

requestItemId

If true, a LearningStoreItemIdentifier for the newly-added item or updated item in the store will be returned in the results.

Return Value

A temporary LearningStoreItemIdentifier that identifies the item being added or updated. This value may be used to reference the item in other commands in this job, but it becomes invalid after the job has been executed. To retrieve a LearningStoreItemIdentifier that is valid after the job has been executed, call this method with requestItemId=true, and the LearningStoreItemIdentifier will be returned as one of the results of the job.

Exceptions
Exception type Condition
ArgumentException

uniquePropertyValues must contain at least one value.

ArgumentNullException

itemTypeName or uniquePropertyValues or propertyValuesToUpdate is a null reference.

System.InvalidOperationException

The item type in itemTypeName doesn't exist in the store, a property name passed in uniquePropertyValues, propertyValuesToUpdate or propertyValuesForAdd doesn't exist on the item type, a property value passed in uniquePropertyValues, propertyValuesToUpdate or propertyValuesForAdd is not a valid value for the corresponding property, or a required property value wasn't passed in.

Remarks

Steps required to add or update an item in a store:

If the item is added, then the values from uniquePropertyValues, propertyValuesToUpdate, and propertyValuesForAdd are stored in the new item. If the item is updated, then the values from propertyValuesToUpdate are updated on the item. The entries in uniquePropertyValues, propertyValuesToUpdate, and propertyValuesForAdd must have values that are valid for the corresponding property. See AddItem for a list of the valid property types. Since the Id property is automatically generated and can not be changed, uniquePropertyValues, propertyValuesToUpdate, and propertyValuesForAdd can not contain a value for the Id property. If an item is added and a value for a property isn't provided, then the default value for the property is used.

If more than one item matches uniquePropertyValues when the job is executed, then an System.InvalidOperationException is thrown.

This operation returns a LearningStoreItemIdentifier as a result if requestItemId is true. It returns nothing as a result if requestItemId is false.

Example

The following code searches for the user item with a User key "Company\JDoe" in the store specified by "store." If the item exists, then the name is changed to "John Doe." If the item does not exist, then a new user item is created with the key "Company\JDoe", the name "John Doe", and an AudioLevel of 0.5:

C#
// Create the unique values
Dictionary<string,object> uniqueValues = new Dictionary<string,object>();
uniqueValues["Key"] = "Company\JDoe";
 
// Create the property values to be updated
Dictionary<string,object> updateValues = new Dictionary<string,object>();
updateValues["Name"] = "John Doe";
 
// Create the property values to be set if the item is added
Dictionary<string,object> addValues = new Dictionary<string,object>();
addValues["AudioLevel"] = 0.5;

// Create a job and add the "add or update item" operation
LearningStoreJob job = store.CreateJob();
job.AddOrUpdateItem("UserItem", uniqueValues, updateValues, addValues, false);
 
// Execute the job
job.Execute();